/*
 * IRemoteInvoker.java   0.0.1    Dec 4, 2009
 * 
 * Copyright (c) 2009 mentalsmash.org
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * The use of the Apache License does not indicate that this project is
 * affiliated with the Apache Software Foundation.
 */
package org.mentalsmash.tazio.net.ril;

import org.mentalsmash.tazio.commons.identifiers.OID;
import org.mentalsmash.tazio.net.ril.exceptions.NoSuchRemoteObjectException;

/**
 * @version 0.0.1 Dec 4, 2009
 * @author Andrea Sorbini <as@mentalsmash.org>
 *
 */
public interface RemoteInvoker {

    public OID getOID();

    /**
     * Returns the {@link RemoteObjectsRegistry} instance used by this
     * RemoteInvoker. This can be used to make local objects available for
     * remote method invocation from other hosts.
     * 
     * @return the RemoteObjectsRegistry instance used by this RemoteInvoker
     */
    public RemoteObjectsRegistry getRegistry();

//    /**
//     * @return the {@link RemoteInvocationDispatcher} instance used by this
//     * RemoteInvoker to send requests to other remote hosts.
//     */
//    public RemoteInvocationDispatcher getDispatcher();
//
//    /**
//     * @return the {@link RemoteInvocationMessageHandler} instance used by this
//     * RemoteInvoker to receive and handle incoming requests from other hosts
//     */
    public RemoteInvocationMessageHandler getMessageHandler();
//
//    /**
//     * 
//     * 
//     * @return the dispatchingLayer
//     */
//    public DispatchingLayerProxy getDispatchingLayerProxy();

    /**
     * Retrieves a {@link RemoteObject} instance linked to the instance
     * registered with the specified {@link OID}.<br/>
     * The returned instance might be cast to any of the interfaces implemented
     * by the original instance registered on the remote host.<br/>
     * If an instance was registered on the local {@link RemoteObjectsRegistry}
     * with the supplied OID then the returned RemoteObject will reference that
     * instance and method invocations will actually execute in the local
     * environment.
     * 
     * 
     * @param oid
     *            an {@link OID} identifying the remote instance
     * @return a {@link RemoteObject} that might be used to invoke methods on
     *         the remote instance
     * @throws NoSuchRemoteObjectException
     *             if the supplied OID doesn't identify any instance in the
     *             local registry or any of the ones on the currently available
     *             remote hosts.
     */
    public RemoteObject getRemoteObject(OID oid)
	    throws NoSuchRemoteObjectException;

    /**
     * Retrieves a {@link RemoteObject} instance linked toe the instance
     * registered with the specified {@link OID} and returning it casted to the
     * interface supplied as argument. If an instance has been registered on the
     * local {@link RemoteObjectsRegistry} with the supplied OID then the
     * returned RemoteObject will reference that instance and method invocations
     * will actually execute in the local environment.
     * 
     * @param <T>
     * @param oid
     * @param objType
     * @return a {@link RemoteObject} that might be used to invoke methods on
     *         the remote instance, casted to the specified interface
     * @throws NoSuchRemoteObjectException
     */
    public <T> T getRemoteObject(OID oid, Class<T> objType)
	    throws NoSuchRemoteObjectException;
    
    
//    public void setRegistry(RemoteObjectsRegistry registry);
//    public void setDispatcher(RemoteInvocationDispatcher dispatcher);
//    public void setMessageHandler(RemoteInvocationMessageHandler handler);
//    public void setDispatchingLayerProxy(DispatchingLayerProxy proxy);
    

    

}